fix(ui): move Comments/CommentForm to emdash/ui/comments subpath (#2039) by scottbuscemi · Pull Request #2044 · emdash-cms/emdash

scottbuscemi · 2026-07-15T01:24:34Z

What does this PR do?

Adds a dedicated emdash/ui/comments entry point for Comments and CommentForm, so their CSS no longer bleeds onto pages that don't render comments — while keeping the barrel re-exports for backwards compatibility.

Astro's CSS scanner processes the entire barrel module when any export is imported. Because Comments.astro and CommentForm.astro were only available via emdash/ui's barrel, a page that only did import { PortableText } from "emdash/ui" pulled their <style> blocks into a shared, render-blocking CSS chunk on every page. This mirrors the existing emdash/ui/search entry point.

Non-breaking (per @ascorbic): the barrel still re-exports Comments/CommentForm with @deprecated JSDoc pointing at emdash/ui/comments. Templates, demos, fixtures, and docs use the new subpath. Barrel re-exports drop in 1.0.

Closes #2039

Reproduction / verification

Built demos/simple (astro build, SSR) before and after the change and grepped the emitted client CSS for ec-comment selectors (when demos import from the subpath):

CSS file (loaded on…)	Before (barrel)	After (this PR)
`Base..css` (shared layout — every page*)	1 ❌	0 ✅
`index.*.css` (home)	0	0
`styles.*.css` (global)	0	0
`_slug_.*.css` (posts page that renders comments)	1	1

Migration (recommended)

-import { Comments, CommentForm } from "emdash/ui";
+import { Comments, CommentForm } from "emdash/ui/comments";

Existing emdash/ui imports continue to work until 1.0.

Type of change

Checklist

I have read CONTRIBUTING.md
pnpm typecheck passes (packages, demos, templates)
pnpm lint passes
pnpm test passes
pnpm format has been run
I have added/updated tests for my changes (verified via a before/after production build CSS comparison — see above)
User-visible strings in the admin UI are wrapped for translation — n/a (no admin UI strings changed)
I have added a changeset
New features link to an approved Discussion — n/a (bug fix)

AI-generated code disclosure

This PR includes AI-generated code — model/tool: Claude Opus 4.8 / grok-4.5 (opencode)

Screenshots / test output

See the before/after CSS table above. Follow-ups from review:

Restored barrel exports as @deprecated (non-breaking)
Added ./ui/comments to RUNTIME_COUPLED (fixes typecheck public-source guard)
Ran ./scripts/sync-template-skills.sh for embedded skill copies

Try this PR

Open a fresh playground →

A full working EmDash site, deployed from this branch. Each visit gets its own session-scoped sandbox: no login needed and no shared state. Try the admin, edit content, hit the public site.

_{Tracks fix/2039-comments-ui-subpath. Updated automatically when the playground redeploys.}

changeset-bot · 2026-07-15T01:24:38Z

🦋 Changeset detected

Latest commit: 201e4b2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages

Name	Type
emdash	Minor
@emdash-cms/cloudflare	Minor
@emdash-cms/sandbox-workerd	Patch
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/do-demo-site	Patch
@emdash-cms/do-solo-demo-site	Patch
@emdash-cms/admin	Minor
@emdash-cms/auth	Minor
@emdash-cms/blocks	Minor
@emdash-cms/gutenberg-to-portable-text	Minor
@emdash-cms/x402	Minor
create-emdash	Minor
@emdash-cms/auth-atproto	Patch
@emdash-cms/plugin-embeds	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-07-15T01:24:43Z

Scope check

This PR touches 25 files. PRs with a broad scope are harder to review. Please confirm the scope hasn't drifted beyond the intended change.

If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs.

See CONTRIBUTING.md for contribution guidelines.

pkg-pr-new · 2026-07-15T01:26:30Z

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/admin@2044

@emdash-cms/auth

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/auth@2044

@emdash-cms/auth-atproto

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/auth-atproto@2044

@emdash-cms/blocks

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/blocks@2044

@emdash-cms/cloudflare

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/cloudflare@2044

@emdash-cms/contentful-to-portable-text

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/contentful-to-portable-text@2044

emdash

npm i https://pkg.pr.new/emdash-cms/emdash@2044

create-emdash

npm i https://pkg.pr.new/emdash-cms/emdash/create-emdash@2044

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/gutenberg-to-portable-text@2044

@emdash-cms/plugin-cli

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-cli@2044

@emdash-cms/plugin-types

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-types@2044

@emdash-cms/registry-client

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/registry-client@2044

@emdash-cms/registry-lexicons

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/registry-lexicons@2044

@emdash-cms/registry-verification

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/registry-verification@2044

@emdash-cms/sandbox-workerd

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/sandbox-workerd@2044

@emdash-cms/x402

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/x402@2044

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-ai-moderation@2044

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-atproto@2044

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-audit-log@2044

@emdash-cms/plugin-color

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-color@2044

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-embeds@2044

@emdash-cms/plugin-field-kit

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-field-kit@2044

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-forms@2044

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/emdash-cms/emdash/@emdash-cms/plugin-webhook-notifier@2044

commit: 201e4b2

cloudflare-workers-and-pages · 2026-07-15T01:27:57Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-playground	`201e4b2`	Jul 17 2026, 06:58 PM

cloudflare-workers-and-pages · 2026-07-15T01:28:01Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-demo-cache	`201e4b2`	Jul 17 2026, 06:59 PM

cloudflare-workers-and-pages · 2026-07-15T01:31:05Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-demo-do	`201e4b2`	Jul 17 2026, 06:56 PM

emdashbot

The approach is correct: moving Comments and CommentForm out of the emdash/ui barrel into emdash/ui/comments is the right fix for the Astro CSS-scanning issue described in #2039, and it mirrors the existing emdash/ui/search entry point. The export map, barrel cleanup, tsconfig exclusion, changeset, and in-repo fixture/demo/template .astro updates are all consistent.

I checked the diff, the changed core files, and searched the tree for remaining Comments/CommentForm imports from emdash/ui. I found one real gap: the canonical skills/building-emdash-site/ docs were updated, but the copies embedded in every template under templates/*/.agents/skills/building-emdash-site/ still instruct users to import comments from the old emdash/ui barrel. Since those copies are tracked files with no sync script, they are now stale and will break (or mislead) anyone scaffolding a site from a template.

I also noted that, while the integration/e2e fixtures now exercise emdash/ui/comments implicitly, there is no automated regression guard for the actual CSS-isolation claim. Given the difficulty of asserting over Astro's emitted CSS, this is a suggestion rather than a blocker.

Conclusion: the fix is sound, but the stale template skill copies need to be updated before merge.

Findings

[needs fixing] templates/blank/.agents/skills/building-emdash-site/SKILL.md:102-111

The canonical skills/building-emdash-site/SKILL.md was updated to import Comments/CommentForm from emdash/ui/comments, but the embedded copy inside every template still shows the old barrel import.
```
import {
	PortableText,
	Image,
	WidgetArea,
	EmDashHead,
	EmDashBodyStart,
	EmDashBodyEnd,
} from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
import LiveSearch from "emdash/ui/search";
```
The same stale example exists in templates/blank/.agents/skills/building-emdash-site/references/site-features.md (line 291) and in the corresponding building-emdash-site copies under templates/blog/, templates/blog-cloudflare/, templates/marketing/, templates/marketing-cloudflare/, templates/portfolio/, templates/portfolio-cloudflare/, templates/starter/, and templates/starter-cloudflare/. Those are real tracked files (not symlinks or generated artifacts), so they need the same update.
[suggestion] packages/core/src/components/index.ts:25-26

The structural fix is clear from this comment, but there is no automated guard against someone re-adding Comments/CommentForm to this barrel in the future. The PR's verification is a manual build comparison; consider adding a regression check (e.g., a build test that greps emitted CSS for ec-comment selectors on a page that does not import emdash/ui/comments, or a static check that components/index.ts does not re-export the comment components).

khoinguyenpham04

Thanks for fixing this, the approach looks good. Just a few things before merging, please check my comments.

Happy to help with the fixes as well.

khoinguyenpham04 · 2026-07-15T09:39:42Z

      "default": "./dist/astro/middleware/redirect.mjs"
    },
    "./ui": "./src/ui.ts",
+    "./ui/comments": "./src/ui-comments.ts",


CI is failing because this points to a raw TypeScript file.

khoinguyenpham04 · 2026-07-15T09:41:01Z

 ```astro
 ---
-import { Comments, CommentForm } from "emdash/ui";
+import { Comments, CommentForm } from "emdash/ui/comments";


Looks like the template copies still have the old import. Try running ./scripts/sync-template-skills.sh should update them all.

ascorbic · 2026-07-15T14:31:47Z

My concern here is that this is a breaking change. Any site that uses comments will break if they upgrade. I think it doesn't need to be: we can add the subpath export for this and the other components, while leaving the barrel untouched. We can then update templates to import from e.g. emdash/ui/pt. Existing sites stay working, but the new templates and docs are updated with the improved optimisation.

scottbuscemi · 2026-07-15T18:34:30Z

I was okay with this being a pre-1.0 breaking change. Less maintenance burden moving forward, no?

ascorbic · 2026-07-16T08:39:50Z

We can remove the barrel in 1.0, but I want to avoid breaking changes unless they're needed. This time I'd suggest addign subpath exports, changing the barrel re-exports to use @deprecated jsdoc comments and changing all the templates and docs to use the new syntax, and then dropping the barrel in 1.0

Their <style> blocks were pulled into a shared, render-blocking CSS chunk on every page that imported anything from the emdash/ui barrel (e.g. PortableText), because Astro scans the whole barrel module graph. Splitting them into a dedicated entry point keeps comment CSS off pages that don't render comments, mirroring the existing emdash/ui/search entry point.

@deprecated

Address ascorbic review: add emdash/ui/comments without breaking existing emdash/ui imports. Mark barrel re-exports @deprecated (remove in 1.0), allowlist the subpath in the public-source guard, and sync template skills.

scottbuscemi · 2026-07-17T18:52:44Z

Updated per @ascorbic's guidance:

Non-breaking — barrel still re-exports Comments / CommentForm with @deprecated JSDoc; remove in 1.0
New subpath — emdash/ui/comments remains the preferred import (templates/demos/docs already use it)
CI — ./ui/comments added to RUNTIME_COUPLED in the public-source guard (was failing typecheck)
Template skills — ran ./scripts/sync-template-skills.sh so embedded skill copies match

Also rebased onto latest main.

github-actions Bot added area/core review/needs-review No maintainer or bot review yet area/templates size/M labels Jul 15, 2026

khoinguyenpham04 added the bot:review Trigger an emdashbot code review on this PR label Jul 15, 2026

emdashbot Bot reviewed Jul 15, 2026

View reviewed changes

github-actions Bot added review/awaiting-author Reviewed; waiting on the author to respond and removed review/needs-review No maintainer or bot review yet labels Jul 15, 2026

khoinguyenpham04 requested changes Jul 15, 2026

View reviewed changes

ascorbic mentioned this pull request Jul 15, 2026

fix(flue-review): recover interrupted workflows #2053

Merged

18 tasks

scottbuscemi added 2 commits July 17, 2026 11:51

fix(ui): keep barrel Comments exports as deprecated (#2039)

201e4b2

Address ascorbic review: add emdash/ui/comments without breaking existing emdash/ui imports. Mark barrel re-exports @deprecated (remove in 1.0), allowlist the subpath in the public-source guard, and sync template skills.

scottbuscemi force-pushed the fix/2039-comments-ui-subpath branch from 375bce7 to 201e4b2 Compare July 17, 2026 18:52

github-actions Bot added review/needs-rereview Author pushed changes since the last review and removed review/awaiting-author Reviewed; waiting on the author to respond labels Jul 17, 2026

Uh oh!

Conversation

scottbuscemi commented Jul 15, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Reproduction / verification

Migration (recommended)

Type of change

Checklist

AI-generated code disclosure

Screenshots / test output

Try this PR

Uh oh!

changeset-bot Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jul 15, 2026

Scope check

Uh oh!

pkg-pr-new Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

emdashbot Bot left a comment

Choose a reason for hiding this comment

Findings

Uh oh!

khoinguyenpham04 left a comment

Choose a reason for hiding this comment

Uh oh!

khoinguyenpham04 Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

khoinguyenpham04 Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

ascorbic commented Jul 15, 2026

Uh oh!

scottbuscemi commented Jul 15, 2026

Uh oh!

ascorbic commented Jul 16, 2026

Uh oh!

scottbuscemi commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

scottbuscemi commented Jul 15, 2026 •

edited by github-actions Bot

Loading

changeset-bot Bot commented Jul 15, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 15, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 15, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 15, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 15, 2026 •

edited

Loading